Skip to main content
Version: Android SDK 6.7.2

Transaction Types

Sale

Sale Method

A sale initiates a payment operation to the card reader. In it's simplest form you only have to pass the amount and currency.

Parameters

ParameterNotes
amount Required
BigInteger
Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency Required
Currency
Currency of the charge
options
SaleOptions
An object to store all the customization options for a sale.

Code example

//Initiate a sale for 10.00 in Great British Pounds
api.sale(new BigInteger("1000"),Currency.GBP);

//Initiate a sale for 10.00 in Great British Pounds with tipping configuration
//This feature is only available for PAX and Telpo devices
TipConfiguration tipConfiguration = new TipConfiguration();
tipConfiguration.setTipPercentages(Arrays.asList(5, 10, 15, 20));
tipConfiguration.setAmount(new BigInteger("1000"));
tipConfiguration.setBaseAmount(new BigInteger("1000"));
tipConfiguration.setEnterAmountEnabled(true);
tipConfiguration.setFooter("Thank you");
tipConfiguration.setSkipEnabled(true);
SaleOptions options = new SaleOptions();
options.setTipConfiguration(tipConfiguration);

api.sale(new BigInteger("1000"),Currency.GBP, options);

Events invoked

currentTransactionStatus

Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry').


signatureRequired

Invoked if card verification requires signature.


endOfTransaction

Invoked when the terminal finishes processing the transaction.


Returns

ParameterNotes
BooleanTrue if the operation was successfully sent to the terminal.

Sale And Tokenize Card

saleAndTokenizeCard Method

A sale operation which also returns a card token. This functionality is not available for all acquirers, please check with Handpoint to know if tokenization is supported for your acquirer of choice.

Parameters

ParameterNotes
amount Required
BigInteger
Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency Required
Currency
Currency of the charge
options
SaleOptions
An object to store all the customization options for a sale.

Code example

//Initiate a sale for 10.00 in Great British Pounds
api.saleAndTokenizeCard(new BigInteger("1000"),Currency.GBP);

//Initiate a sale for 10.00 in Great British Pounds with tipping configuration
//This feature is not available for HiLite devices
TipConfiguration tipConfiguration = new TipConfiguration();
tipConfiguration.setTipPercentages(Arrays.asList(5, 10, 15, 20));
tipConfiguration.setAmount(new BigInteger("1000"));
tipConfiguration.setBaseAmount(new BigInteger("1000"));
tipConfiguration.setEnterAmountEnabled(true);
tipConfiguration.setFooter("Thank you");
tipConfiguration.setSkipEnabled(true);
SaleOptions options = new SaleOptions();
options.setTipConfiguration(tipConfiguration);

api.saleAndTokenizeCard(new BigInteger("1000"),Currency.GBP,options);

Events invoked

currentTransactionStatus

Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry').


signatureRequired

Invoked if card verification requires signature.


endOfTransaction

Invoked when the terminal finishes processing the transaction.


Returns

ParameterNotes
BooleanTrue if the operation was successfully sent to the terminal.

Sale Reversal

saleReversal Method

A sale reversal, also called sale VOID allows the user to reverse a previous sale operation. This operation reverts (if possible) a specific sale identified with a transaction id. In its simplest form you only have to pass the amount, currency and originalTransactionID but it also accepts a map with extra parameters. Note that transactions can only be reversed within a 24 hours timeframe or until the daily batch of transactions has been sent for submission.

Parameters

ParameterNotes
amount Required
BigInteger
Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency Required
Currency
Currency of the charge
originalTransactionID Required
String
Id of the original sale transaction
options
MerchantAuthOptions
An object to store all the customization options for the transaction.

Code example

//Initiate a reversal for 10.00 in Great British Pounds
api.saleReversal(new BigInteger("1000"),Currency.GBP,"00000000-0000-0000-0000-000000000000");

Events invoked

currentTransactionStatus

Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry').


signatureRequired

Invoked if card verification requires signature.


endOfTransaction

Invoked when the terminal finishes processing the transaction.


Returns

ParameterNotes
BooleanTrue if the operation was successfully sent to the terminal.

Refund

refund Method

A refund operation moves funds from the merchant account to the cardholder´s credit card. In it's simplest form you only have to pass the amount and currency but it also accepts a map with extra parameters. Note that a card is required to be swiped, dipped or tapped for this operation. For Interac (Canadian Debit Network), refunds can only be processed until Interac closes the batch of transactions at night.

Parameters

ParameterNotes
amount Required
BigInteger
Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency Required
Currency
Currency of the charge
originalTransactionID
String
If present it links the refund with a previous sale. It effectively limits the maximum amount refunded to that of the original transaction.
options
RefundOptions
An object to store all the customization options for a refund.

Code example

//Initiate a refund for 10.00 in Great British Pounds
api.refund(new BigInteger("1000"),Currency.GBP,"00000000-0000-0000-0000-000000000000");

Events invoked

currentTransactionStatus

Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry')


signatureRequired

Invoked if card verification requires signature.


endOfTransaction

Invoked when the terminal finishes processing the transaction


Returns

ParameterNotes
BooleanTrue if the operation was successfully sent to the terminal.

Refund reversal

refundReversal Method

A refund reversal, also called refund VOID allows the merchant to reverse a previous refund operation. This operation reverts (if possible) a specific refund identified with a transaction id. In it's simplest form you only have to pass the amount, currency and originalTransactionID but it also accepts a map with extra parameters. Note that transactions can only be reversed within a 24 hours timeframe or until the daily batch of transactions has been sent for submission.

Parameters

ParameterNotes
amount Required
BigInteger
Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency Required
Currency
Currency of the charge
originalTransactionID Required
String
transaction id of the original refund
options
MerchantAuthOptions
An object to store all the customization options for the transaction.

Code example

//Initiate a refund reversal for 10.00 in Great British Pounds
api.refundReversal(new BigInteger("1000"),Currency.GBP,"00000000-0000-0000-0000-000000000000");

Events invoked

currentTransactionStatus

Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry').


signatureRequired

Invoked if card verification requires signature.


endOfTransaction

Invoked when the terminal finishes processing the transaction.


Returns

ParameterNotes
BooleanTrue if the operation was successfully sent to the terminal.

MoTo Sale

MoToSale Method

Mail Order /Telephone Order (MOTO) sale. MOTO is a type of card-not-present (CNP) transaction in which services are paid and delivered via telephone, mail, fax, or internet communication. MOTO has become synonymous with any financial transaction where the entity taking payment does not physically see the card used to make the purchase.

Calling this operation will trigger the MOTO input form on the payment terminal, the MOTO form requires the merchant to enter the card number, expiry date and check value (CVV) of the card before processing the transaction.

Parameters

ParameterNotes
amount Required
BigInteger
Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency Required
Currency
Currency of the charge
options
MoToOptions
An object to store optional parameters for a MoTo sale.

Code example

MoToOptions options = new MoToOptions();
options.setCustomerReference("MoTo Sale Example");

api.motoSale(new BigInteger("1000"), Currency.EUR, options);

Events invoked

currentTransactionStatus

Invoked during a transaction, it fetches statuses coming from the sdk (ex : 'processing').


endOfTransaction

Invoked when the terminal finishes processing the transaction.


Returns

ParameterNotes
BooleanTrue if the operation was successfully sent to the gateway.

MoTo Refund

moToRefund Method

A Mail Order/Telephone Order (MOTO) refund operation moves funds from the merchant account to the cardholder´s credit card. In it's simplest form you only have to pass the amount and currency but it also accepts the original transaction id. MOTO Refund is a type of card-not-present (CNP) transaction in which services are refunded via telephone, mail, fax, or internet communication. MOTO has become synonymous with any financial transaction where the entity taking payment does not physically see the card used to make the purchase or refund.

Calling this operation will trigger the MOTO input form on the payment terminal, the MOTO form requires the merchant to enter the card number, expiry date and check value (CVV) of the card before processing the transaction.

Parameters

ParameterNotes
amount Required
BigInteger
Amount of funds to charge - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
currency Required
Currency
Currency of the charge
originalTransactionId
String
If present, it links the refund with a previous sale. It effectively limits the maximum amount which can be refunded to the amount of the previous sale.
options
MoToOptions
An object to store optional parameters for a MoTo refund.

Code example

MoToOptions options = new MoToOptions();
options.setCustomerReference("MoTo Refund Example");

api.motoRefund(new BigInteger("1000"), Currency.EUR, "00000000-0000-0000-0000-000000000000",options);

Events invoked

currentTransactionStatus

Invoked during a transaction, it fetches statuses coming from the sdk (ex : 'processing').


endOfTransaction

Invoked when the terminal finishes processing the transaction.


Returns

ParameterNotes
BooleanTrue if the operation was successfully sent to the gateway.

MoTo Reversal

moToReversal Method

A MOTO reversal, also called VOID allows the user to reverse a previous sale/refund operation. This operation reverts (if possible) a specific operation identified with a transaction id. Note that transactions can only be reversed within a 24 hours timeframe or until the daily batch of transactions has been sent for submission. MOTO Reversal is a type of card-not-present (CNP) transaction used to reverse a previous MOTO Sale or MOTO Refund.

Parameters

ParameterNotes
originalTransactionId Required
String
Id of the original sale transaction.
options
MoToOptions
An object to store optional parameters for a MoTo reversal.

Code example

MoToOptions options = new MoToOptions();
options.setCustomerReference("MoTo Reversal Example");

api.motoReversal("00000000-0000-0000-0000-000000000000",options);

Events invoked

currentTransactionStatus

Invoked during a transaction, it fetches statuses coming from the sdk (ex : 'processing').


endOfTransaction

Invoked when the terminal finishes processing the transaction.


Returns

ParameterNotes
BooleanTrue if the operation was successfully sent to the gateway.

Signature result

signatureResult Method

A signatureRequired event is invoked during a transaction when a signature verification is required, for example when a payment is done with a swiped or chip and signature card. The merchant is required to ask the cardholder for signature and approve (or decline) the transaction. signatureResult tells the payment terminal if the signature was approved by passing the value true in the method. To decline a signature event then false should be passed to the payment terminal. Note that this event is only required for an HiLite integration and can be safely ignored for a PAX or Telpo integration.

Parameters

ParameterNotes
accepted Required
Boolean
pass true if merchant accepts cardholder signature

Code example

//Approves signature automatically in signatureRequired event
@Override
public void signatureRequired(SignatureRequest signatureRequest, Device device){
api.signatureResult(true);
}

Events invoked

currentTransactionStatus

Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry').


endOfTransaction

Invoked when the terminal finishes processing the transaction.


Returns

ParameterNotes
BooleanTrue if the operation was successfully sent to the terminal.

Tip Adjustment

TipAdjustment Method

A tip adjustment operation allows merchants to adjust the tip amount of a sale transaction before the batch of transactions is settled by the processor at the end of the day. Note: This functionality is only available for the restaurant industry in the United States and the processors currently supporting this functionality are TSYS and VANTIV. This functionality is limited to HiLite terminals.

Dependencies: The code example provided depends on RxJava, take a look a their documentation to see how to easily include this dependency in your android project. If you do not want to use RxJava or any additional dependencies then AsyncTask, provided by android, can be used instead for this asynchronous processing. Still we recommend using RxJava as it improves readability and maintainability.

Parameters

ParameterNotes
tipAmount Required
BigDecimal
Tip amount added to the original (base) transaction amount - in the minor unit of currency (f.ex. 1000 is 10.00 GBP)
originalTransactionID Required
String
Unique id of the original sale transaction as received from the card reader (EFTTransactionID)

Code example

Observable.fromCallable(new Callable() {
@Override
public FinancialStatus call() throws Exception {
return api.tipAdjustment(new BigDecimal(1000), "2bc23910-c3b3-11e6-9e62-07b2a5f091ec");
}
})
.subscribeOn(Schedulers.io())
.observeOn(AndroidSchedulers.mainThread())
.subscribe(new Consumer() {
@Override
public void accept(@NonNull FinancialStatus status) throws Exception {
if (status == FinancialStatus.AUTHORISED) {
//SUCCESS
} else if (status == FinancialStatus.DECLINED) {
//DECLINED
} else {
//FAILED
}
});

Returns

FinancialStatus

Result of the tip adjustment transaction, it returns a FinancialStatus, the possible values are :

ParameterNotes
FinancialStatus- FinancialStatus.AUTHORISED (tip adjustment approved by the processor)
- FinancialStatus.FAILED (system error or timeout)
- FinancialStatus.DECLINED (tip adjustment declined by the processor).

If two tip adjustments are sent for the same sale transaction, the second tip adjustment will override the first one. In case the transaction fails (not declined) we recommend that you prompt the user of the POS to retry the adjustment.

Tokenize Card

tokenizeCard Method

Returns a card token (representing the card number). This functionality is not available for all acquirers, please check with Handpoint to know if tokenization is supported for your acquirer of choice.

Parameters

ParameterNotes
options
Options
An object to store all the customization options for the transaction.

Code example

//Tokenize a card
api.tokenizeCard();

Events invoked

currentTransactionStatus

Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry').


endOfTransaction

Invoked when the terminal finishes processing the transaction.


Returns

ParameterNotes
BooleanTrue if the operation was successfully sent to the terminal.

Card PAN

cardPan Method

danger

This transaction type will ONLY work on PAX/Telpo devices. On HiLite payment terminals it is not available.

A cardPan request will return the full PAN of the card being swiped, dipped or tapped. Only the PANs of whitelisted card ranges will be returned by the Handpoint systems. This operation is mostly used to be able to process funds or points from loyalty cards.

Parameters

ParameterNotes
options
Options
An object to store all the customization options for the transaction.

Code example

//Gets the PAN of a card
api.cardPan();

Events invoked

currentTransactionStatus

Invoked during a transaction, it fetches statuses coming from the terminal (ex : 'waiting for card' or 'waiting for PIN entry').


endOfTransaction

Invoked when the terminal finishes processing the transaction.


Returns

ParameterNotes
BooleanTrue if the operation was successfully sent to the terminal.